home *** CD-ROM | disk | FTP | other *** search
-
- The Sozobon C Compiler
-
- eXtended Version
-
- a freeware offering
- maintained by Jerry G. Geiger
-
- based on the SOZOBON 2.00 release
- by
- Sozobon, Limited
-
-
-
- Users Reference
-
-
-
- 1. Introduction
-
- The Sozobon C Compiler is a complete implementation of the C
- language as defined by Kernighan & Ritchie and prevailing
- practice. It is on the way to being compatible with ANSI/POSIX
- standards. The package includes a compiler, optimizer, assembler,
- linker, and several other associated utilities. For runtime
- library support, xdlibs, a library based on the public domain
- dLibs routines and some other different libraries are used.
-
- This extended SOZOBON version is based on Sozobon 2.00 (c) by
- Sozobon Ltd: Tony Andrews, Johann Ruegg, and Joe Treat.
- It's Runtime library is based on dLibs library by Dale Schumacher.
- The GEM libary is based on GEMFast library by Ian Lepore.
-
-
- 1.1 Copyright and Disclaimer
-
- Like the original library packages and original Sozobon versions,
- the eXtended Version of the Sozobon compiler including all
- executables and other components may be freely distributed.
-
- The extended version of the Sozobon C compiler can be freely
- distributed, as long as you don't modify the copyright and mark
- changed parts clearly.
- You may not charge any money for copying the three Sozobon
- archives, or their contents or parts of them. You may not include
- them in any public domain/Shareware disk libraries for the
- purposes of sale (even for a minimal charge).
-
- IN NO EVENT WILL I AND/OR ANY OTHER PARTY BE LIABLE TO YOU FOR DAMAGES,
- INCLUDING ANY LOST PROFITS, LOST MONIES, OR OTHER SPECIAL, INCIDENTAL
- OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE
- (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED
- INACCURATE OR LOSSES SUSTAINED BY THIRD PARTIES OR A FAILURE OF THE
- PROGRAMS TO OPERATE WITH OTHER PROGRAMS) THE PROGRAMS, EVEN IF YOU HAVE
- BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES, OR FOR ANY CLAIM BY
- ANY OTHER PARTY.
- This goes for the libraries too, of course.
-
- Berlin, Nov 1993 and again now: Mar 2 1994, October 1994,
- February 1995
- Jerry G. Geiger
- Aachen, Sep 1995
- Volker Seebode
-
-
-
- 2. Development Environment
-
- This section describes in more detail the operation of the
- compiler and the relationship between parts of the compiler and
- the corresponding pieces of the Alcyon compiler.
-
- The compiler works best when used with a shell like 'bash', 'tcsh',
- 'mupfel' or similiar.
-
- There is a special GEM based shell called C-Desk, by Holger Weets,
- for those who dislike make-files and command line environments.
-
- The compiler should be usable on machines with 512K and a single
- disk. This document does not describe the optimal layout for
- various ST configurations, but you can probably figure out what
- makes the most sense for your machine. This will probably
- involve a RAM disk, and some arrangement of programs and
- libraries on one or more floppies.
-
- 2.1 Environment Variables
-
- Several environment variables may be used to alter the operation
- of the compiler. The variables are used to specify the location
- of executables, header files, libraries, and temporary files.
-
- Some variables may reference a list of directories to be searched,
- with elements of the list separated by commas or semicolons. The
- variables are:
-
- SOZBIN
- PATH (executables, list of paths)
- (\usr\bin)
- (where make and cc find the components, ':' are
- possible as seperators, too)
- INCLUDEDIR (std header file path: one path)
- hcc replaces the builtin paths with this path
- (\usr\include)
- SOZINC,
- INCLUDE list of directories with header files
- used instead of builtins or $INCLDUEDIR
- LIBDIR (libraries, startup modules: one path)
- (\usr\lib)
- SOZLIB,
- LIB list of directories with libraries
- used instead of builtins or $LIBDIR
- TMPDIR (temporary files: one path)
- (\usr\tmp)
- If you have not specified a LIBDIR or INCLUDEDIR variable, the builtin
- pathes are searched for if $INCLUDE or $LIB isn't set.
-
- cc or hcc and ld will built their own $LIB / $INCLUDE if these
- variables are not set from the $LIBDIR and $INCLUDEDIR pathes and
- some builtin names. While hcc and ld only handle the 'xdlibs'
- directory in this pathes, cc can switch to different libraries with
- the --mint --c68 and --dlibs options.
-
- So cc assumes to find in the path $INCLUDEDIR the directories
- 'xdlibs', 'mntinc' and 'dlibs' with the special library header files
- in them. A INCLUDE variable built by cc from
- INCLUDEDIR=u:\usr\include
- would be:
- INCLDUE=u:\usr\include\xdlibs,u:\usr\include
-
- A $LIB variable built by cc would be in the same case (default) with a
- LIBDIR=u:\usr\lib
- specified:
- LIB=u:\usr\lib\sozobonx\xdlibs,u:\usr\lib\sozobonx
- and with the --mint option:
- LIB=u:\usr\lib\sozobonx\mntlib,u:\usr\lib\sozobonx
-
-
- 2.2 Recommanded Directory Structure
-
- Unpacking the distribution will create this structure in a
- directory 'sozdistr' but not in '\usr'.
-
- \usr\bin\
- cc.ttp, hcc.ttp, ... (all the executables)
- \usr\include\
- xdlibs\...
- mntinc\...
- dlibs\...
- ... (general header files)
- \usr\lib\
- sozobonx\
- xdlibs\...
- mntlib\...
- dlibs\...
- ... (general SozobonX libraries)
- c68\
- xdlibs\...
- mntlib\...
- ... (general c68 libraries)
-
-
- 3. Types and Other Compiler Dependencies
-
- 3. 1. The supported data types and their sizes (in bytes) are:
-
- void 0
- char 1
- short 2
- int 2 (switchable to 4)
- long 4
- unsigned char 1
- unsigned short 2
- unsigned int 2 (switchable to 4)
- unsigned long 4
- float 4
- double 8 (IEEE)
- POINTER 4
-
-
- Floating point math is supported using the "Fast Floating Point"
- representation documented by Motorola and IEEE format for doubles.
- Both 'float' and 'double' types are supported, but printf() e.g.
- only supports doubles.
-
- Any of the basic data types may be declared as register variables.
- Pointers occupy the A registers, all other types are placed in D
- registers. Six data registers and five address registers are
- available for use by register variables.
-
- 3.2 Compiler Limits
-
- Some limits imposed by the Sozobon compiler are:
-
- * Local variables are limited to a total of 32K in size per
- function.
-
- * The size of a single structure may not exceed 32K.
-
- * Include files may not be nested more than 8 deep.
-
- * Identifiers may be of any length, and are case significant.
-
- * Arrays may not exceed 0x80000000 bytes, so the largest index of
- a char array is 0x7fffffff. Arrays larger than 64K
- may cause some trouble, but they should work.
-
- * The switch expressions may be of any integer type (char, short,
- or long).
-
- 3.3 Constants and implicit types
-
- * The resulting type of sizeof() is unsigned int by default.
- There is a warning generated if sizeof() exceeds 64K, in which
- case you should assign the sizeof() expression to a long
- variable. If the result exceeds 0x7fffffff Bytes an error
- message is printed. Since HCC pl34 you may switch the type
- of sizeof() to unsigned long.
-
- * Integer constants are of the smallest type they fit in (char,
- short, or long) unless they are noted as octal or hexadecimal
- constants, which are unsigned by default. You can force a
- constant to be a long value using hexadecimal notation with
- leading '0' characters; '0x0000ff00' will be long like
- '0xff00L'
-
- * Arrays' index expressions are normally casted to long integer.
-
-
- 3.4 extensions to K&R compatibility
-
- * bit fields - now standard fields: first in decl is MSB
-
- * long bit fields implemented ( unsigned long foo : 25; )
-
- * enumerations
-
- * structure assignment
-
- * structure parameters
-
- * structure return values
-
- * assembly escapes
-
- * multibyte constants
-
- * ANSI function declarations
-
- * type checking of arguments to parameters in function calls
-
- * void type, pointer to void
-
- * string concats
-
- * variable Parameters ('...') in function declarations
-
- * all ANSI keywords
-
- Most of the features listed above are self-explanatory. Assembly
- code can be embedded within C using the following syntax:
-
- asm("assembly code");
-
- The string within quotes is passed directly to the output file.
- It is preceded by a tab, and followed by a newline, so these do
- not need to be given in the string. Extreme caution should be
- used when running the optimizer on C code that contains assembly
- escapes. For access to variables put the name of the variable in
- angle-brackets like:
-
- asm(" move.l #1, <i>");
-
- 3.5 Missing ANSI C compatibility
-
- Not implemented is:
-
- * type checking of arguments to parameters in function calls
-
- * the keywords const and volatile are not working at all
-
- * '#elif' is not known to the builtin preprocessor
-
-
-
- 4.0 The components of Sozobon eXtended version
-
-
- The binaries are maintained by different people now! So please
- read in the man files where to send your bugreports. Please mention
- the version and patchlevel you can find with '-V' option or the
- 'ident' tool you may have in your enviroment!
-
- This is not a complete description of all the binaries of Sozobon.
- If you have installed Sozobon completely you will have access to
- the detailed description in the man files (typing 'man <name>' or
- using the ST-Guide HyperText system). Maybe you have printed them.
-
- The excutables will (soon) know all some common options. The
- directly called ones (make, cc, ar, nm, ipc and mkptypes) will
- accept the following multiletter options:
-
- --version
- Print a detailed version description and exit.
-
- --help
- Print a help-page (short description of all options) and exit.
-
- All will know the following options:
-
- -V (same as --version)
-
- -v verbose output
-
- -h (same as --help) or a usage message (hcc, top, jas, ld)
-
-
- 4.1 cc - run the compiler components
-
- The features and options are discribed in file cc.man, which is a
- copy of man\cat1\cc.1 you have copied in your $MANPATH\cat1 directory.
-
- This is the most important program if you use SOZOBONX with
- makefiles or in a cli shell (e.g. Gemini's console window). It
- will run all the passes to generate an excutable or object
- modules.
-
- The compiler converts your source code to assembly language so
- that the optimizer can optimize it, the assembler can convert it
- to an object file, and the linker can generate an executable from
- it and some library stuff.
-
- cc now supports another compiler, Thorsten Roskowetz's c68 port, too.
- It should be available in an archive 'sozc68<nn>.lzh', including a
- MiNT library for this compiler. Therefore Scotts Bigham's 'cpp' is
- now included in the SozobonX distribution.
-
-
- 4.2 hcc - The Compiler
-
- The compiler generates error messages if there are problems with
- your source code. It includes a preprocessor wich can handle
- statements like:
-
- #assert <expression>
-
- If expression is false the compile session aborts.
-
- #error "string"
-
- The compile session will stop, and error <string> will be
- displayed.
-
- #pragma <option> <arguments>
-
- For information on #pragma commands, see the manual file (hcc.man).
-
-
- The following MACROS are implemented:
- These are'defined', and you can manipulate them:
-
- MC68000, mc68000, SOZOBON (value is 0x200)
- ATARI_ST, TOS, __TOS__, __SOZOBONX__ (value is current version),
- __MSHORT__ (if ints are of type short) __STDC__
-
- These conatain strings with usefull information, you can not change
- them, except the first two, with a special preprocessor statement.
- (see man file for more details)
- __LINE__, __FILE__, __BASE_FILE__, __VERSION__
- __TIME__, __DATE__, __SDATE__, __STIME__, __GDATE__
-
-
- The compiler uses the "normal" 68000 C calling conventions.
- Register A6 is used as a frame pointer, and function return
- values are placed in D0.
-
- gemdos(), bios() and xbios() calls are replaced by quasi-inline
- functions - the trap instruction is generated.
-
-
- floating point arithmetics
-
- The compiler supports float types (4 Bytes, Motorola's fast floating
- point scheme) and double types - the IEEE 64 Bit values.
- Think of: the math library functions and printf() only accept
- double values.
-
-
- bit fields
-
- Are now standard fields: first bit in decl, or more precise MSB in
- first expession of the bit field declaration is MSB in the whole
- field.
- There are long bit fields implemented now, exceeding 16 bits for
- single expression: (e.g. unsigned long foo : 25; )
-
-
- 4.2.1 Profiling
-
- To use profiling, invoke cc with the -p option. The compiler will
- generate additional code: At begin of every function a function
- 'void _prolog(char funcname[])' and at end a function
- 'void _epilog(char funcname[])' is called. They count the
- number of calls to each function, and time each call. To get this
- profiling information you have to call the function
- 'void _safeprof()'.
-
- All these functions exist in the library (file extended.lib). The
- funktion '_safeprof()' writes all of the profiling stuff to a file
- called '.\prof.out'. If you use the 'prof_s.o' startup module,
- this function is automatically called when your program exits. cc
- will make use of this startup module if called with option '-p'.
- You can of course repleace these functions by your own ones.
-
- 4.2.2 Source Level Debugging
-
- To use source level debugging, invoke cc/hcc with the Option
- '-X<n>[function]'. The compiler generates additional code
- according to level <n> in the option. You can specify a function
- which is called by this code at the begin and end of every
- function reached at runtime. In loops this function is usually
- called, too. If you don't specify a function, only the line
- number and the file name the module was compiled from is saved.
- You can use the function '_debug' from the library file
- 'libextra.a' or write an own function. If you specify level 2
- with the <n> option this function is called one time for every
- line in the source code. If you don't specify a function at all,
- the level option is ignored. The exception signals are caught then,
- and an error message is printed via Salert() function, or written
- to stderr if not available. The special modules used for this
- feature (except.a) will be told the linker, if you call
- cc with the '-X'option.
-
- The above mentioned function '_debug()' from libraray archive
- 'libextra.a' is the interface to Holger Weets' and Christian
- Wempes's source level debugger. If you specify this function with the
- '-X' option, it is linked into your program.
- This debugger uses BIOS console for output, and assumes 24 lines
- in the output window. It will prompt for an command after
- invocation by the _debug() function:
- --------------
- Sozobon Online Debugger V1.0 -- Written by C. Wempe & H. Weets, 1992
- current position: line <number> of file <source file>
- >
- --------------
- Where line <number> is the number of the line in the <source file>
- from which the current code is compiled.
-
- The following commands are implemented:
-
- ? - display this help
- b [file [start [end]]] - show/set breakpoint and position
- c [start [count]] - display lines of source file
- f - free loaded file
- g [cnt] - continue with program
- l [filename] - Load file (default: actual file)
- m [start [end]] - memory dump
- n - display actual line
- q - quit program (call exit)
- r - display registers
- t - toggle meaning of return key
- x - exit debugging (never return)
- reg=value - set value of register (reg = d0-d7,a0-a7)
- reg&value - mask register
- [$|%]number - displays <number> in DEC, BIN and HEX
-
- 4.2.3
-
- For more information and the commandline options see the hcc man
- file (hcc.man)
-
-
- 4.3 top - The Optimizer
-
- The optimizer can vastly improve your program; executed between
- the compiler and the assembler, the optimzer removes segments of
- code that are not efficient and replaces them with code that is.
- When variables can be registered (for faster access) this is also
- done. For more information about the optimizer, please consult
- the manual file (top.man).
-
-
- 4.4 jas - The Assembler
-
- The assembler converts the output of the compiler into an object
- file so that the linker can deal with it. It can read usual
- Motorola 68000 assembler code, written by hand, too. For more
- information about the assembler, please consult the manual file
- (jas.man).
-
-
- 4.5 ld - The Linker
-
- The linker is the last step performed in a compilation; it takes
- all of the source code modules of a program and gathers them into
- a single object file, then prepends the startup code to the object
- and takes some used functions from the libraries, to form an
- executable program. For more information on the linker, please
- consult the ld manual file (ld.man).
-
-
- 4.6 The Libraries
-
- SOZOBON eXtended version comes along with XdLibs, based on the the
- dLibs library routines, written by Dale Schumacher. A GEM library
- is included, too. It is based on Ian Lepore's GEMfast library.
- A ST-Guide hypertext documentation of the libraries is to find
- in this distribution, made by Michel Forget from XdLibs.doc
- and the other library doc files.
-
- You can tell 'cc' what runtime library you want to be linked; it will
- get the right file and the right starupcode:
-
- default is : (taking libs from 'sozobonx' directory)
- -mshort
- xdlibs/crt0.o (startup) and xdlibs/libc.a (library) for some
- functions you need ty specify '-lextra' to get
- xdlibs/libextra.a as additional library
-
- other options:
- --dlibs
- dstart.o and dlibs.a get used
-
- --mint (the libraries will soon exist)
- mntlib/ctr0.o and mntlib/libc.a are used
-
- -mlong (not yet implemented, for the libraries don't exist)
- xdlibs/crt032.o and xdlibs/libc32.a will get used.
-
- --c68 (libraries are taken form c68 directory, not the
- sozobonx one; this will change soon cause c68 is
- nearly compatible to hcc)
-
- 4.6.1 Startup Code
-
- The startup code is the entry point of a program, doing some basic
- things, and not at least calling your 'main()' function.
- So the startup modules are used to link programs. Different moduls
- are in this distribution, the default startup module is 'crt0.o'.
- In the file 'soz_libs.hyp' you will find a chapter about startup
- modules, and the file 'startup.txt' is the same in ascii.
-
-
- 4.6.2 XdLibs The C Runtime Library
-
- See the file 'xdlibs.doc' for a complete documentation of the runtime
- library. It is included in the 'soz_libs.hyp' hyper text file, too.
- The standard library modules are to find in the files 'libc.a'
- and 'libextra.a'. The last one contains rarely used functions and
- extensions to the C standard library.
- With this release 'libc.a' contains all floating point code, too.
-
- One traditional problem with C compilers and floating point is that
- as soon as you call printf(), you wind up linking in a bunch of
- floating point code whether you need it or not. To avoid this
- problem there is now a different solution:
-
- There is an additional library 'libci.a' which is used by cc unless
- you specify '-f' or '-lm', it's the integer only library with no
- floating point support at all.
- There may be libraries like 'libi.a' e.g. in MiNT directory containing
- printf and scanf routines for integer only programs. You will have to
- write a '-li' in cc's commandline to make use of them.
-
-
- 4.6.3 libm.a The Mathematics Floating Point Library
-
- Just add '-lm' to your commandline and cc will force ld to
- link from the math library 'libm.a'. You don't need an extra '-f'
- cc won't use the integer only library with this argument.
-
- The library itself is a port of the 'pml' - portable math library
- by Fred Fish.
-
-
- 4.6.4 GEM libraries
-
- You will find two GEM libraries in this distribution, xvdifast.a
- and xaesfast.a. They are bug-fixed and/or extended versions of
- the well known gemfast library.
-
-
- 4.6.5 utility libraries
-
- Some utility libraries are added to this distribution (util.a and
- gemlib.a).
-
-
- 4.7 make
-
- Now there is a make.man in this distribution, and you will find
- a file make.doc - discussing make in general.
-
- make is a tool to make something, not only programs from source
- code. You can describe what is to do and the relationships among
- the files in a 'makefile'; and each time you change some files the
- simple shell command 'make' suffices to perform all necessary
- actions (recompilations). make knows how to make an executable from
- source files and can learn new rules, too.
-
-
- 4.8 ipc The Include Pre Compiler
-
- This program by Holger Weets will precompile your header files, to
- get them read faster by hcc. Since header ('*.h') files rarely
- change, this utility was created to allow you to compile them in
- advance so that they do not have to be compiled every time your
- source code is compiled. This can greatly speed up the
- compilation process. For more information on the include file
- precompiler, please read the manual file (ipc.man).
-
-
- 4.9 mkptypes Make Function Prototypes
-
- The mkptypes program will generate header files from C source files,
- to be included as global access function declarations in any
- header files, or as static function declarations in your sourcefiles.
- Please read the manual file (mkptypes.man).
-
- 4.10 library utilities
-
- 4.10.1 nm
-
- The 'nm' program dumps the symbol table of object files,
- libraries, and executables. The output is not in standard form,
- yet. See manual (nm.man).
-
- 4.10.2 ar
-
- The 'ar' program manages libraries, especially of object modules.
- See manual (ar.man).
-
- 4.10.3 har Holger's Archiver.
-
- This is a 'ar' utility with a GEM/AES interface for interactive
- dealing with library archives.
-
-
- 4.11 pflags
-
- The pflags program sets and shows execution flags in the program
- header. See manual for details (pflags.man).
-
-
- 4.12 tagfile Make Tag Files
-
- This utility generates 'tagfiles' from source files, for usage by
- C-Desk and QED/ACE or e.g. your editor - if you can tell it what a
- tagfile is for. The tagfiles are used by the debugger 'debug' to
- get some information about the bug's location, too.
-
-
- 4.13 clint
-
- This program is not standard 'lint' utility, but was written by
- Holger Weets for testing and checking source code as well. There is
- no english documentation available this time, maybe soon.
-
-
- 4.15 debug Debugger
-
- A small debugger by Holger Weets just to get some information
- where a exception causing bug is located in your source files.
- (It makes use of existing tagfiles)
-
- 4.16 szadb Debugger
-
- Not in this distribution, I am going to ask Michal Jaegermann
- for support.
-
- 4.17 Some unchanged programs from original Sozobon 2.00 distribution:
-
- * The 'size' utility prints the size of text, data, and bss
- for objects, libraries, and executables.
-
- * The 'globs' program isn't very useful unless you have the
- Alcyon compiler. It removes local symbols from object
-
- -eof-
-